Update pagination documentation

Updated to include details on the various properties that are included
on paginated result pages. Also added some example JSON.

Part of https://github.com/mysociety/popit-api/pull/37