Improve the autorefresh documentation

Remove the claims that refreshing and notifications happen "immediately"
as they're actually only enqueued immediately, and go into a bit more
detail about how things work.
Fix a bunch of small errors in the RLMRealm docs
Improve the migration documentation

Move the main explanation of stuff from the documentation block for the
typedef to the doc blocks for the methods and (hopefully) improve the
wording a bit. While this results in most of the documentation being
duplicated, appledoc doesn't actually document typedefs so it didn't
show up in the generated HTML at all previously.
Fix some typos
Improve the migration documentation more
Merge pull request #828 from realm/tg-autorefresh-docs

Improve the RLMRealm documentation a bit