MONGOID-5363 Document that upsert replaces existing documents (#5293)

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: p-mongo

docs/reference/crud.txt

@@ -191,10 +191,12 @@ operations with examples.
 
    * - ``Model#upsert``
 
-       *Performs a MongoDB upsert on the document. If the document exists in the database,
-       it will get overwritten with the current attributes of the document in memory.
-       If the document does not exist in the database, it will be inserted. Note that
-       this only runs the* ``{before|after|around}_upsert`` *callbacks.*
+       *Performs a MongoDB replace with upsert on the document. If the document
+       exists in the database, it will get overwritten with the current
+       document in the application (any attributes present in the database but
+       not in the application's document instance will be lost).
+       If the document does not exist in the database, it will be inserted.
+       Note that this only runs the* ``{before|after|around}_upsert`` *callbacks.*
      -
         .. code-block:: ruby