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: I917f1819066520a81cfaac1c9e884a1bf359d59c
Closes-Bug: #1370184
Merge "Update ironic states and documentation"