docs: Update README and add comprehensive async documentation

- Update README.rst with complete async support information
- Replace outdated "experimental" async section with comprehensive features
- Document intentionally deferred features with clear reasoning
- Add docs/guide/async-support.rst with 700+ lines of detailed async usage guide
- Include migration guide, limitations, workarounds, and best practices
- Add async-support to docs/guide/index.rst toctree

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: jeonghanjoo

README.rst

@@ -127,10 +127,10 @@ Some simple examples of what MongoEngine code looks like:
     >>> BlogPost.objects(tags='mongodb').count()
     1
 
-Async Support (Experimental)
-============================
-MongoEngine now supports asynchronous operations using PyMongo's AsyncMongoClient.
-This allows you to use async/await syntax for database operations:
+Async Support
+=============
+MongoEngine provides comprehensive asynchronous support using PyMongo's AsyncMongoClient.
+All major database operations are available with async/await syntax:
 
 .. code :: python
 
@@ -142,22 +142,93 @@ This allows you to use async/await syntax for database operations:
         # Connect asynchronously
         await connect_async('mydb')
 
-        # All document operations have async equivalents
+        # Document operations
         post = TextPost(title='Async Post', content='Async content')
         await post.async_save()
-
-        # Async queries
-        post = await TextPost.objects.async_get(title='Async Post')
+        await post.async_reload()
         await post.async_delete()
 
-        # Async reload
-        await post.async_reload()
+        # QuerySet operations
+        post = await TextPost.objects.async_get(title='Async Post')
+        posts = await TextPost.objects.filter(tags='python').async_to_list()
+        count = await TextPost.objects.async_count()
+        
+        # Async iteration
+        async for post in TextPost.objects.filter(published=True):
+            print(post.title)
+
+        # Bulk operations
+        await TextPost.objects.filter(draft=True).async_update(published=True)
+        await TextPost.objects.filter(old=True).async_delete()
+
+        # Reference field async fetching
+        # In async context, references return AsyncReferenceProxy
+        if hasattr(post, 'author'):
+            author = await post.author.async_fetch()
+
+        # Transactions
+        from mongoengine import async_run_in_transaction
+        async with async_run_in_transaction():
+            await post1.async_save()
+            await post2.async_save()
+
+        # GridFS async operations
+        from mongoengine import FileField
+        class MyDoc(Document):
+            file = FileField()
+        
+        doc = MyDoc()
+        await MyDoc.file.async_put(file_data, instance=doc)
+        
+        # Context managers
+        from mongoengine import async_switch_db
+        async with async_switch_db(MyDoc, 'other_db'):
+            await doc.async_save()
 
-    # Run the async function
     asyncio.run(main())
 
-Note: Async support is experimental and currently includes basic CRUD operations.
-QuerySet async methods and advanced features are still under development.
+**Supported Async Features:**
+
+- **Document Operations**: async_save(), async_delete(), async_reload()
+- **QuerySet Operations**: async_get(), async_first(), async_count(), async_create()
+- **Bulk Operations**: async_update(), async_delete(), async_update_one()
+- **Async Iteration**: Support for ``async for`` with QuerySets
+- **Reference Fields**: async_fetch() for explicit dereferencing
+- **GridFS**: async_put(), async_get(), async_read(), async_delete()
+- **Transactions**: async_run_in_transaction() context manager
+- **Context Managers**: async_switch_db(), async_switch_collection()
+- **Aggregation**: async_aggregate(), async_distinct()
+- **Cascade Operations**: Full support for all delete rules (CASCADE, NULLIFY, etc.)
+
+**Current Limitations:**
+
+The following features are intentionally not implemented due to low priority or complexity:
+
+- **async_values()**, **async_values_list()**: Field projection methods
+  
+  *Reason*: Low usage frequency in typical applications. Can be implemented if needed.
+
+- **async_explain()**: Query execution plan analysis
+  
+  *Reason*: Debugging/optimization feature with limited general use.
+
+- **Hybrid Signal System**: Automatic sync/async signal handling
+  
+  *Reason*: High complexity due to backward compatibility requirements. 
+  Consider as separate project if needed.
+
+- **ListField with ReferenceField**: Automatic AsyncReferenceProxy conversion
+  
+  *Reason*: Complex implementation requiring deep changes to ListField.
+  Manual async dereferencing is required for now.
+
+**Migration Guide:**
+
+- Use ``connect_async()`` instead of ``connect()``
+- Add ``async_`` prefix to all database operations: ``save()`` → ``async_save()``
+- Use ``async for`` for QuerySet iteration
+- Explicitly fetch references with ``await ref.async_fetch()`` in async context
+- Existing synchronous code remains 100% compatible when using ``connect()``
 
 Tests
 =====