Improve documentation about /api/stats API

After going through really long hours of research, we came up with a pretty good understanding of the whats and whys of the `/api/stats` API.

Let's block some time to document them before all this knowledge goes away 🙂 

File containing the API: https://github.com/elastic/kibana/blob/master/src/legacy/server/status/routes/api/register_stats.js?rgh-link-date=2020-08-17T21%3A35%3A10Z#L109