docs: document the RequestQueueClient v4 migration

Expand the `RequestQueueClient` migration table in the v4 upgrading guide with
the full method mapping, the new fetch/handle/reclaim lifecycle, the
`isEmpty` semantics, and the `RequestQueueV1`-as-alias note. List the removed
head/lock types.

Closes #3075.

Author: janbuchar

docs/upgrading/upgrading_v4.md

@@ -560,11 +560,28 @@ The sub-client interfaces (`DatasetClient`, `KeyValueStoreClient`, `RequestQueue
 
 **`RequestQueueClient`:**
 
+The request queue client was reduced from 12 methods to 9. The distributed-locking protocol (`listAndLockHead` → `prolongRequestLock` → `deleteRequestLock`) and the queue-head/consistency bookkeeping that used to live in the `RequestQueue` frontend have been removed from the interface; coordinating multiple clients accessing the same queue (e.g. request locking on the Apify platform) is now an internal concern of the client implementation.
+
 | Before (v3) | After (v4) |
 |---|---|
+| `addRequest(request, opts?)` | `addBatchOfRequests([request], opts?)` |
+| `batchAddRequests(requests, opts?)` | `addBatchOfRequests(requests, opts?)` |
+| `getRequest(id)` | `getRequest(uniqueKey)` |
+| `updateRequest(request, opts?)` | `markRequestAsHandled(request)` / `reclaimRequest(request, opts?)` |
+| `listHead(opts?)` | `fetchNextRequest()` (returns a single request, marks it in progress) |
+| `listAndLockHead(opts)` | Removed (locking is internal to the client) |
+| `prolongRequestLock(id, opts)` | Removed |
+| `deleteRequestLock(id, opts?)` | Removed |
 | `deleteRequest(id)` | Removed |
+| _(n/a)_ | `isEmpty()` (new — `true` when no pending requests remain) |
+
+The lifecycle is now: `fetchNextRequest()` hands out a pending request and marks it in progress; once processed, call `markRequestAsHandled(request)`; on failure call `reclaimRequest(request, { forefront? })` to return it to the queue.
+
+`RequestQueueClient.isEmpty()` reports whether any **pending** request remains (i.e. whether the next `fetchNextRequest()` would return `null`); requests that are in progress are not counted.
+
+`RequestQueueV1` and `RequestQueueV2` no longer differ in behavior — both are thin frontends over the slim client — and `RequestQueueV1` is now a deprecated alias of `RequestQueue`.
 
-**Removed types** from `@crawlee/types`: `DatasetClientUpdateOptions`, `KeyValueStoreClientUpdateOptions`, `KeyValueStoreRecordOptions`, `KeyValueStoreClientListData`, `KeyValueStoreClientGetRecordOptions`. `KeyValueStoreClientListOptions` was renamed to `KeyValueStoreListKeysOptions`.
+**Removed types** from `@crawlee/types`: `DatasetClientUpdateOptions`, `KeyValueStoreClientUpdateOptions`, `KeyValueStoreRecordOptions`, `KeyValueStoreClientListData`, `KeyValueStoreClientGetRecordOptions`, `QueueHead`, `RequestQueueHeadItem`, `ListOptions`, `ListAndLockOptions`, `ListAndLockHeadResult`, `ProlongRequestLockOptions`, `ProlongRequestLockResult`, `DeleteRequestLockOptions`. `KeyValueStoreClientListOptions` was renamed to `KeyValueStoreListKeysOptions`.
 
 The high-level storage classes (`Dataset`, `KeyValueStore`, `RequestQueue`) now receive their sub-client directly in the constructor options instead of receiving a `StorageClient` and calling its methods.