docs: Upgrade upgrading guide

docs/04-upgrading/upgrading_to_v2.md

@@ -11,9 +11,12 @@ Support for Python 3.8 has been dropped. The Apify Python SDK v2.x now requires
 
 ## Storages
 
-The SDK now uses [crawlee](https://github.com/apify/crawlee-python) for local storage emulation. This change should not affect intended usage (working with `Dataset`, `KeyValueStore` and `RequestQueue` classes from the `apify.storages` module or using the shortcuts exposed by the `Actor` class) in any way.
-
-Removing the `StorageClientManager` class is a significant change. If you need to change the storage client, use `crawlee.service_container` instead.
+- The SDK now uses [crawlee](https://github.com/apify/crawlee-python) for local storage emulation. This change should not affect intended usage (working with `Dataset`, `KeyValueStore` and `RequestQueue` classes from the `apify.storages` module or using the shortcuts exposed by the `Actor` class) in any way.
+- There is a difference in the `RequestQueue.add_request` method: it accepts an `apify.Request` object instead of a free-form dictionary. 
+    - A quick way to migrate from dict-based arguments is to wrap it with a `Request.model_validate()` call.
+    - The preferred way is to instantiate it directly, e.g., `Request(url='https://example.tld', ...)`, or using the `Request.from_url` helper which prefills the `unique_key` and `id` attributes.
+    - For simple use cases, `add_request` also accepts plain strings that contain an URL.
+- Removing the `StorageClientManager` class is a significant change. If you need to change the storage client, use `crawlee.service_container` instead.
 
 ## Configuration
 
@@ -28,6 +31,7 @@ Attributes suffixed with `_millis` were renamed to remove said suffix and have t
 - `Actor.start`, `Actor.call`, `Actor.start_task`, `Actor.set_status_message` and `Actor.abort` return instances of the `ActorRun` model instead of an untyped `dict`.
 - Upon entering the context manager (`async with Actor`), the `Actor` puts the default logging configuration in place. This can be disabled using the `configure_logging` parameter.
 - The `config` parameter of `Actor` has been renamed to `configuration`.
+- Event handlers registered via `Actor.on` will now receive Pydantic objects instead of untyped dicts. For example, where you would do `event['isMigrating']`, you should now use `event.is_migrating`
 
 ## Scrapy integration