diff --git a/README.rst b/README.rst
index 96ebb84d..6ceb3ed2 100644
--- a/README.rst
+++ b/README.rst
@@ -131,3 +131,54 @@ Possible response codes are for various requests include:
 - HTTP 501 Not Implemented - The requested URL is valid but the handler isn't
   implemented yet.
 - HTTP 503 Service Unavailable - The service is down, possibly for maintanance.
+
+Module Build States
+-------------------
+
+You can see the list of possible states with::
+
+    import rida
+    print(rida.BUILD_STATES)
+
+Here's a description of what each of them means:
+
+init
+~~~~
+
+This is (obviously) the first state a module build enters.
+
+When a user first submits a module build, it enters this state.  We parse the
+modulemd file, learn the NVR, and create a record for the module build.
+
+Then, we validate that the components are available, and that we can fetch
+them.  If this is all good, then we set the build to the 'wait' state.  If
+anything goes wrong, we jump immediately to the 'failed' state.
+
+wait
+~~~~
+
+Here, the scheduler picks up tasks in wait and switches to build immediately.
+Eventually, we'll add throttling logic here so we don't submit too many builds for the build system to handle.
+
+build
+~~~~~
+
+The scheduler works on builds in this state.  We prepare the buildroot, submit
+builds for all the components, and wait for the results to come back.
+
+done
+~~~~
+
+Once all components have succeeded, we set the top-level module build to 'done'.
+
+failed
+~~~~~~
+
+If any of the component builds fail, then we set the top-level module build to 'failed' also.
+
+ready
+~~~~~
+
+This is a state to be set when a module is ready to be part of a
+larger compose.  perhaps it is set by an external service that knows
+about the Grand Plan.
diff --git a/rida.py b/rida.py
index 8b067fd5..f5a322b4 100755
--- a/rida.py
+++ b/rida.py
@@ -123,7 +123,7 @@ def submit_build():
         build = rida.database.ComponentBuild(module_id=module.id, package=pkgname, format="rpms")
         db.session.add(build)
     module.modulemd = mmd.dumps()
-    module.state = rida.database.BUILD_STATES["init"]
+    module.state = rida.database.BUILD_STATES["wait"]
     db.session.add(module)
     db.session.commit()
     # Publish to whatever bus we're configured to connect to.
diff --git a/rida/database.py b/rida/database.py
index 62706968..26c60da0 100644
--- a/rida/database.py
+++ b/rida/database.py
@@ -41,11 +41,27 @@ from sqlalchemy.ext.declarative import declarative_base
 
 # Just like koji.BUILD_STATES, except our own codes for modules.
 BUILD_STATES = {
+    # When you parse the modulemd file and know the nvr and you create a
+    # record in the db, and that's it.
+    # publish the message
+    # validate that components are available
+    #   and that you can fetch them.
+    # if all is good, go to wait: telling ridad to take over.
+    # if something is bad, go straight to failed.
     "init": 0,
+    # Here, the scheduler picks up tasks in wait.
+    # switch to build immediately.
+    # throttling logic (when we write it) goes here.
     "wait": 1,
+    # Actively working on it.
     "build": 2,
+    # All is good
     "done": 3,
+    # Something failed
     "failed": 4,
+    # This is a state to be set when a module is ready to be part of a
+    # larger compose.  perhaps it is set by an external service that knows
+    # about the Grand Plan.
     "ready": 5,
 }