OP-5810 - documentation updates to include new returned values and new p...

...arameters for purchases.

Some screen shots...

The V3 Deal changes:
![screen shot 2014-10-01 at 2 12 09 pm](https://cloud.githubusercontent.com/assets/358891/4484941/98f26a0e-49c2-11e4-96cd-37eac65f2c39.png)

V3 Deal parameter update:
![screen shot 2014-10-01 at 2 12 33 pm](https://cloud.githubusercontent.com/assets/358891/4484942/98f4b1a6-49c2-11e4-9d56-061402a9abb5.png)

V1 parameter update:
![screen shot 2014-10-01 at 2 12 45 pm](https://cloud.githubusercontent.com/assets/358891/4484944/98f93726-49c2-11e4-99cd-fd3aad60d0a7.png)

V1 deal item updates:
![screen shot 2014-10-01 at 2 13 54 pm](https://cloud.githubusercontent.com/assets/358891/4484943/98f6cad6-49c2-11e4-968d-cad261446c05.png)

Changed this around to try to make what `deal_items` are and how they are output a bit more clear.

@tonybove have at me again.