Update ironic states and documentation

This adds doc strings for the various states, and updates the documentation
header to reflect the current state of states.

In addition, this removes the following unused states:
  - INIT
  - BUILDING
  - SUSPEND

Change-Id: Id7493e856504f5ccf67fe7a716d748ffa7248590
Closes-Bug: #1308207
Merge "Update ironic states and documentation"